home *** CD-ROM | disk | FTP | other *** search
/ Aminet 23 / Aminet 23 (1998)(GTI - Schatztruhe)[!][Feb 1998].iso / Aminet / misc / emu / IBMConv.lha / IBMConv / Doc1.21.doc < prev    next >
Text File  |  1997-11-17  |  21KB  |  469 lines
  1.                     IBMConv Version 1.21 Documentation.
  2.                             © 1992 D Trollope.
  3.  
  4.                               The legalities.
  5.  
  6.    Permission is granted to distribute this archive provided that:
  7.  
  8.    1. It is not distributed in part, the whole archive must be distributed.
  9.    2. It is not used in a commercial environment for commercial purposes.
  10.          (This could be arranged though...)
  11.    3. This notice is included in all copies.
  12.    4. Modified copies are marked below with the author name and modification
  13. details, and I am notified.
  14.    5. All parts of the archive (code,documentation and executables) are
  15. © 1992,1993 D Trollope, and although you are quite welcome to examine and make
  16. use of it, don't distribute it as yours.
  17.    6. If you like the program why not make a donation to the author... This
  18. archive is Public Domain though.
  19.  
  20.    This version has not been modified by anybody but the original author -
  21. D Trollope
  22.  
  23.    No liability is accepted for the contents of the archive containing this and
  24. other files relating to IBMConv. Use these files at your own risk.
  25.  
  26.    The following should be included in this archive.
  27.  
  28.    Documentation.DOC    The documentation file.
  29.    IBMConv.h            C Header file included by IBMConv.c
  30.    IBMConv.c            C Source code for the executable provided.
  31.                            (Lattice C V5.1)
  32.    IBMConv              CLI executable program.
  33.    Contents.DOC         A cutting of this section of documentation.
  34.                            (You obviously have this!)
  35.    IBMFile.DOC          A Dummy text file in IBM format for you to
  36.                         experiment on.
  37.    AmigaFile.DOC        A Dummy text file in Amiga format for you to
  38.                         experiment on.
  39.  
  40.    If something is missing, ask your source why!
  41.  
  42.                             The documentation.
  43.  
  44.    This is a simple program which will read a text file and convert it to either
  45. IBM/ST format, or AMIGA/UNIX format. To the non techies, this means that extra
  46. control codes will be added/removed where appropriate when transferring text
  47. files.
  48.    Note, this program will NOT read IBM/ST compatible disks, use CrossDOS,
  49. MessyDOS, or DOS2DOS for this.
  50.  
  51.  
  52.    Using IBMConv.
  53.  
  54.    IBMConv has four CLI arguments, there are keywords available to identify
  55. them, but they can be ignored. Three arguments must be specified with or without
  56. the keywords. These are the FROM, TO, and TYPE arguments. The fourth is an
  57. option to stop any output being displayed (except errors). This option is called
  58. QUIET:
  59.  
  60. IBMConv [FROM] Sourcefile [TO] Destinationfile [TYPE] Sourcefiletype [QUIET]
  61.                  AmigaDOS file pathnames              IBM or AMIGA   No output
  62.         [NOXPND]
  63.         No destination
  64.         filename expansion
  65.         New to Version 1.21
  66.  
  67.    Sourcefile and Destinationfile.
  68.  
  69.    These are the files (with optional paths) a) to be read, and b) to be
  70. written.
  71.    The destination does not have to specify a filename. You can give a directory
  72. as the destination. You must supply an actual file (including its path) as the
  73. source name.
  74.  
  75.    IBMConv MS1:Text RAM: IBM
  76.  
  77.    The above line will now work in this version, previous versions would have
  78. failed.
  79.    Keywords can now be specified like this:
  80.  
  81.    IBMConv FROM MS1:Text TO RAM: TYPE IBM
  82.  
  83.    You can now just supply a destination directory without a file. You may
  84. however supply the '/' of the directory. This is not needed though.
  85.    The sourcefile name can be used in the destination directory.
  86.  
  87.    WARNING.
  88.    If you supply a destination file which already exists, or a directory
  89. containing a file with the same name as the original file, a warning is given,
  90. but the file is overwritten. No confirmation is given.
  91.  
  92.    Sourcefiletype
  93.  
  94.    This must be either "IBM" or "AMIGA" and is now case insensitive, ie.
  95. "Amiga", "amiga", "AmIgA" will all be recognised as "AMIGA". Previous versions
  96. were limited to upper case. All keywords are case insensitive.
  97.  
  98.    The QUIET option prevents any output from being displayed during convertion.
  99. The only exception to this is if an error occurs.
  100.  
  101.    The NOXPND option prevents the program expanding the destination file. What
  102. this means is, if a directory or device was supplied, the filename was added to
  103. it. Eg.
  104.  
  105.    IBMConv FROM RAM:Test.txt TO T: TYPE AMIGA
  106.  
  107.    The destination therefore became 'T:Test.txt'. However, some devices didn't
  108. like this, NIL: for example doesn't allow filenames. If you specified a filename
  109. AmigaDOS asked for the volume NIL:
  110.    Using the NoXpnd option forces the program to use the destination file as it
  111. is supplied. NIL: can therefore be used. While using NIL: seems pointless, it
  112. can be used for seeing how long a file is in bytes (after convertion) and lines.
  113. I also can find it useful for debugging when I don't want to save the output.
  114. The third and final reason for this option, is that I do not know if any devices
  115. will be produced in the future with the restriction of no filenames. If one is
  116. produced, the program will be (in theory) compatible with it. I believe a little
  117. forward thinking never hurt anyone did it?
  118.    The only point I will make with this option is if you supply a directory like
  119. 'T:' and used the NoXpnd option, you will receive a DOS error 210, but what do
  120. you expect?
  121.  
  122.    IBMConv FROM RAM:Test.txt TO NIL: TYPE AMIGA NOXPND
  123.  
  124.    The above line works.
  125.  
  126.    Examples.
  127.  
  128.    To convert an Amiga text file (called Test.txt found in the RAM disk) to IBM
  129. format ready for transfer to an IBM disk try the following:
  130.  
  131.    IBMConv FROM RAM:Test.txt TO T:TestIBM.txt TYPE AMIGA
  132. or
  133.    IBMConv RAM:Test.txt T:TestIBM.txt AMIGA
  134.  
  135.    This reads "Convert the AMIGA text file RAM:Test.txt to IBM format and place
  136. it in the file T:TestIBM.txt".
  137.  
  138.    To do the opposite, convert an IBM text file (called Test.txt found in the
  139. RAM disk) that has already been transferred to the Amiga to an Amiga
  140. formatted disk, try the following:
  141.  
  142.    IBMConv FROM RAM:Test.txt TO T:TestAmiga.txt TYPE IBM
  143. or
  144.    IBMConv RAM:Test.txt T:TestAmiga.txt IBM
  145.  
  146.    Supply just a destination directory such as:
  147.  
  148.    IBMConv FROM RAM:Test.txt TO T: TYPE AMIGA        } All Do
  149. or
  150.    IBMConv RAM:Test.txt T: AMIGA                     }
  151. or
  152.    IBMConv FROM RAM:Test.txt TO RAM:T/ AMIGA         } The Same
  153. or
  154.    IBMConv RAM:Test.txt RAM:T/ AMIGA                 }
  155. or
  156.    IBMConv FROM RAM:Test.txt TO RAM:T AMIGA          } Operation
  157. or
  158.    IBMConv RAM:Test.txt RAM:T AMIGA                  }
  159.  
  160.    You can use some, but do not need all the keywords such as:
  161.  
  162.    IBMConv FROM RAM:Test.txt T: TYPE AMIGA
  163.  
  164.    It makes no difference. You can in fact supply keywords, in a different
  165. order, like this:
  166.  
  167.    IBMConv TO T: FROM RAM:Test.txt TYPE AMIGA
  168.  
  169.    Missing the TO keyword is also allowed, as long as the FROM keyword exists.
  170.    The following will work!
  171.  
  172.    IBMConv T: FROM RAM:Test.txt TYPE AMIGA
  173.  
  174.    However, missing the TO and FROM keywords will not work in this case:
  175.  
  176.    IBMConv T: RAM:Test.txt TYPE AMIGA               ; will not be allowed.
  177.  
  178.    To stop any output being displayed
  179.    (with the exceptions of warnings and errors):
  180.  
  181.    IBMConv RAM:Test.txt T: AMIGA QUIET
  182.  
  183.    I hope you understand its use, if not, experiment on the two dummy text files
  184. supplied. Convert the documentation too if you want, but make sure you use
  185. backups!
  186.  
  187.    To examine the files, I recommend using the HEX option in the AmigaDOS
  188. command TYPE because using TYPE on its own shows no difference between the files
  189. in a normal shell. When looking at the HEX values, look for the occurence (or
  190. disappearance depending on the direction of transfer) of values 0D followed by
  191. 0A.
  192.  
  193.                                   Errors.
  194. Number   Message
  195.    101   Minimum number of parameters is 3.
  196.             The are 4 (7 with keywords) possible parameters, 3 of which are
  197.             always needed. This means at least 3 should be specified.
  198.    102   Maximum number of parameters is 7.
  199.             The are 4 (7 with keywords) possible parameters, 7 of which is the
  200.             maximum when all the parameters have been used. This means at least
  201.             1 has been specified more than once, or extra irrelevant parameters
  202.             have been specified in the command line.
  203.    106   No file type has been supplied in the command line.
  204.             You haven't specified "IBM" or "AMIGA" in the command line.
  205.    107   1 file type please, more than 1 has been found in the command line.
  206.             The keyword "IBM" or "AMIGA" has been found in the command line more
  207.             than once. The "TYPE" keyword may have been used once, and not in
  208.             another occurence.
  209.    108   File type must be "IBM" or "AMIGA" (case insensitive).
  210.             The "TYPE" keyword has been specified but the word following is not
  211.             either of the keywords "IBM" or "AMIGA".
  212.    111   No destination file has been supplied in the command line.
  213.             The program cannot find a destination file. If you have supplied one
  214.             there may be a problem with other command line parameters, or a
  215.             space has been missed. Try placing the "FROM" keyword in front of
  216.             your file name (or path). This may not make it work, but will help
  217.             show the command line error.
  218.    112   Only 1 destination file please, more than 1 has been found in the
  219.          command line.
  220.             More than one destination file has been found. If you have supplied
  221.             one there may be a problem with other command line parameters, or a
  222.             space has been missed. Try placing the "FROM" keyword in front of
  223.             your file name (or path). Also use the "TO" keyword, and place '"'s
  224.             around the filenames (not the keywords, just the name. This may not
  225.             make it work, but will help show the command line error.
  226.    113   No destination lock has been possible.
  227.             An AmigaDOS Lock has not been possible on the destination file/
  228.             directory, and the program is not sure if the directory exists, or
  229.             if it is a file name that has been supplied.
  230.    116   No source file has been supplied in the command line.
  231.             The program cannot find a source file. If you have supplied one
  232.             there may be a problem with other command line parameters, or a
  233.             space has been missed. Try placing the "FROM" keyword in front of
  234.             your file name (or path). This may not make it work, but will help
  235.             show the command line error.
  236.    117   Only 1 source file please, more than 1 has been found in the command
  237.          line.
  238.             More than one source file has been found. If you have supplied one
  239.             there may be a problem with other command line parameters, or a
  240.             space has been missed. Try placing the "FROM" keyword in front of
  241.             your file name (or path). Also use the "TO" keyword, and place '"'s
  242.             around the filenames (not the keywords, just the name. This may not
  243.             make it work, but will help show the command line error.
  244.    255   Internal Error - MAXUSER_ERR.
  245.             This should never occur, but if it does contact me immediately, a
  246.             problem with the actual execution has arisen. Try re-executing the
  247.             command. If the problem persists, try playing around with the
  248.             command line parameters. A really persistant problem should be
  249.             attempted after a reboot then if all has failed contact me.
  250.  
  251.    Please note, these are not DOS error numbers, as you will see they have no
  252. meaning regarding AmigaDOS.
  253.                                  Warnings.
  254.  
  255. Number   Message
  256.    101   Binary codes have been found in source file.
  257.  
  258.    If extra binary codes are found in the file, a warning is given to the user.
  259. This does not include tabs, they are not counted as binary codes. Extra symbols
  260. such as '©' or 'ª' are also not counted as binary.
  261.    This warning may appear if the either the file actually has extra binary
  262. codes, or if the file is not of the type specified. EG. If you supply an AMIGA
  263. file specifying as an IBM file, the warning will appear. This is because the
  264. program will be expecting different sequence of binary codes in certain places.
  265.  
  266.    102   Warning, Bad end of line sequence found.
  267.  
  268.    New to version 1.21.
  269.    This warning will appear in conjuction with the binary code warning. It is
  270. displayed when a 0x0d code is found and it is not followed by a 0x0a, or vice
  271. versa in IBM source files. When 0x0d is found in an Amiga source file this
  272. message is also displayed.
  273.  
  274.    103   Warning, Destination file being overwritten.
  275.  
  276.    Previously known as warning 102.
  277.    If you supply a destination file which already exists, or a directory
  278. containing a file with the same name as the original file, a warning is given,
  279. but the file is overwritten. No confirmation is given.
  280.  
  281.    104   Warning, Quiet option selected more than once.
  282.  
  283.    Previously known as warning 103.
  284.    The QUIET option has been registered, but found more than once in the command
  285. line. The program will continue as if only one QUIET option existed.
  286.  
  287.    105   Warning, NoXpnd option selected more than once.
  288.  
  289.    New to version 1.21.
  290.    The NoXpnd option has been registered, but found more than once in the
  291. command line. The program will continue as if only one NoXpnd option existed.
  292.  
  293.                       I do have a few hints on use...
  294.  
  295.    I use the program in conjunction with MessyDOS. Assuming you have a
  296. MessyDOS device MS1: setup you can directly read from an IBM disk using
  297. IBMConv:
  298.  
  299.    IBMConv MS1:AUTOEXEC.BAT RAM: IBM
  300.  
  301.    IBMConv uses the MessyDOS device to access the source file directly, and
  302. write the converted file to the RAM disk. You could just as easily have changed
  303. directory to MS1:, then typed:
  304.  
  305.    IBMConv AUTOEXEC.BAT RAM: IBM
  306.  
  307.    Make sure the IBMConv program is directly available to the shell though!
  308.  
  309.    For all you people who download stuff from NPDSA via an IBM, here is a method
  310. of transferring the UU-Encoded file to the Amiga, converting it to an Amiga
  311. format file, AND decoding it to the decoded archive at once!
  312.  
  313.    Lets assume you wish to download the file PROGRAM.UUE from the IBM disk you
  314. hold in your hand using MessyDOS.
  315.  
  316.    From a shell, CD to the directory you want the decoded file to appear and
  317. type:
  318.  
  319.    run IBMConv MS1:PROGRAM.UUE PIPE:TRANSFER IBM
  320.    UUDecode PIPE:TRANSFER
  321.  
  322.    Using the above method reduces the need to convert the file to the Amiga,
  323. saving it, converting it to Amiga format and then decoding it to another disk.
  324. You just read the file directly, and write the decoded file directly. Easy huh?
  325.  
  326.    The commands RUN, IBMConv, and UUDecode should be immediately available to
  327. the shell, I usually place them in RAM:, and make RUN resident.
  328.    PIPE: and MS1: should be mounted also.
  329.  
  330.                             Compiling IBMConv.
  331.  
  332.    IBMConv can be compiled by 'LC -L IBMConv.c'.
  333.    This version has been developed using Lattice C V5.1.
  334.    Versions 1.0, and 1.1 were developed on version 4.0. I do not believe it to
  335. be V4.0 compatible because the INCLUDE files I originally developed it with were
  336. slightly different, but I could be wrong on this. Let me know if you know
  337. different.
  338.  
  339.                              Bugs in IBMConv, Past and Present.
  340.  
  341.    Version 1.2
  342.  
  343.    Version 1.2 was released with a major bug, 0x0d followed by 0x0a would not
  344. get converted when 0x0d was the last character in the buffer and 0x0a being the
  345. first of the next buffer. In the previous release I said 'I am confident that
  346. this release is bug free, but they could be my fatel last words!', It was my
  347. fatel (well almost) last words, it had not been totally fixed.
  348.  
  349.    Version 1.21
  350.  
  351.    This is the current release.
  352.    
  353.    I cannot say that I am aware of any bugs at the moment, but as I have said
  354. before, and have found out the hard way, has anybody ever written a bug free
  355. program? However, the bug which I thought I had fixed at the last moment in
  356. version 1.2 reoccurred, this is now fixed, I am absolutely positive of this
  357. (I think!).
  358.    Previous versions gave the binary warning when it (correctly) found a
  359. control Z, this code is often found at the end of MSDOS files and is now
  360. suppressed. The warning will still occur if it is found elsewhere in the file.
  361. The code is not copied to the destination if it is the last character in the
  362. source.
  363.    All resources are now freed if the program is interupted by CTRL C etc. I
  364. did not class this as a bug previously, just a drawback with using C, but now
  365. its fixed, I found out how to call the deallocation routine when the program
  366. exits, even if it's caused by a break etc.
  367.    Please, Let me know if you find any bugs, providing as much information as
  368. possible. My address is given below.
  369.  
  370.                                   Future.
  371.  
  372.    There are a number of things I intend to do, and they are listed below.
  373.  
  374.    Use even better dynamic memory allocation methods.
  375.    Allow a specified amount of memory to be used.
  376.    Tidy up the ParseCLIArgs function.
  377.    Add an option to output the prompt etc. to a window defined by the program.
  378.    Provide a decent front end.
  379.    Include a confirmation for overwriting destination files, and appropriate
  380. command line option to force overwriting.
  381.  
  382.    If you have any ideas please forward them to me.
  383.  
  384.                                  History.
  385.  
  386. Version 1.0
  387.  
  388.    This was extremely slow, and the IBM/AMIGA option operated differently,
  389. it said the file type being written, but I felt that to indicate the source
  390. file type made more sense so V1.1 came about. Besides, only I have version 1.0!
  391.  
  392. Version 1.1
  393.  
  394.    A buffer system was added using 2K, in theory speeding up the program, and
  395. it did, about 50% faster... I don't claim it to be fast though!!
  396.    IBM/AMIGA option changed, see above, it now indicates the source file type.
  397.    A progress report is now given, a full stop appears for every 2K read.
  398.    If an error occurs during opening a file, a new error message outputting the
  399. DOS error number has been added.
  400.  
  401. Version 1.2
  402.  
  403.    Previous code was not overly accurate when referencing LONG variables, not
  404. set to 0L, just 0, and displayed using %d rather than %ld. Sorry, This is now
  405. corrected.
  406.    A new buffer system has been employed for source AND destination files, work
  407. being carried out in the buffers. The reason behind this is I expected it to be
  408. faster than the system in 1.1. Now an 8K buffer is allocated for the source
  409. file, and depending on the direction of transfer, a destination buffer of
  410. 8K/10K is allocated, and worked upon. This new system is between 9 to 10 times
  411. faster than version 1.1. It is quite fast. An example of this is that a file
  412. of approx 45K took approximately 1 minute 35 seconds (95 seconds), this version
  413. takes approximately 5 seconds!
  414.    The IBM/AMIGA switch is now case insensative, ie. "Amiga", "amiga", "AmIgA",
  415. will all be recognised as "AMIGA". Previous versions were limited to upper
  416. case.
  417.    A new progress report has been employed displaying the number of bytes read
  418. and written.
  419.    An additional feature showing the number of lines processed has been added.
  420. I thought it might come in useful.
  421.    The 'QUIET' option has been added.
  422.    A warning is now displayed if extra binary codes are found in the file being
  423. converted.
  424.  
  425.      Version 1.21
  426.  
  427.      Apart from the bug fix which is explained in the 'Bugs' section,
  428.      very little has been done to the program.
  429.      The code has been changed to be closer to the C standard
  430.      conventions (variables using lower case etc.).
  431.  
  432.      Two functions have been used in place of the inline code in the
  433.      function main. These functions convert one buffer to the second.
  434.      This was carried out because it makes it easier to see what is
  435.      happening in the function main. The code has been optimised in
  436.      places to try to keep it fast but readable. I could probably make
  437.      it faster, but less understandable!
  438.  
  439.      The 'NOXPND' option has been added.
  440.  
  441.      Two new warnings have been added too. Warning 102 now becomes
  442.      `Warning, Bad end of line sequence found.'. Old warnings 102, 103
  443.      now become 103,104 respectively. 105 refers to multiple use of the
  444.      NOXPND option.
  445.  
  446.      All resources are now freed if the program is interrupted by
  447.      CTRL-C etc.
  448.      My main priority with this release was to get the bug fixed,
  449.      because it did cause problems with large files.
  450.  
  451.      The program also now uses WARN and ERROR return codes. If a
  452.      warning occurs, WARN is returned, no matter which warning it was.
  453.      Any error causes ERROR to be returned. FAIL is not supported,
  454.      because it is very difficult with this program to decide where to
  455.      draw the line between ERROR and FAIL.
  456.  
  457.                                  Contact.
  458.  
  459.      If you want to get hold of me, try the following address. and there
  460.      is no reason for it to change in the near future. It will probably
  461.      be correct for many years to come, but as with any of part of this
  462.      archive, there is no guarantee!
  463.  
  464.      65 Ascham Road           EMail dave.trollope@lucent.com
  465.      Grange Park
  466.      Swindon
  467.      SN5 6BE          
  468.      England
  469.